home *** CD-ROM | disk | FTP | other *** search
/ Aminet 16 / Aminet 16 (1996)(GTI - Schatztruhe)[!][Dec 1996].iso / Aminet / dev / src / wangisrc.lha / wangi / z / SFPatch / SFPatch.doc < prev    next >
Text File  |  1995-07-11  |  3KB  |  91 lines
  1.                   SFPatch.h -- How to use SetFunction
  2.  
  3.  
  4. All functions in Amiga .libraries can be replaced by using the exec function
  5. SetPatch(). The problem is that very little examples exist. This example/toolkit
  6. is based on the source of WBTitle by Mark Thomas.
  7.  
  8. USAGE
  9. ~~~~~
  10.  
  11. SFPatch.h is a file which you can include in your source to make patching very
  12. easy. It is currently only for SAS/C. A few simple steps are required:
  13.  
  14. 1. #include "SFPatch.h"
  15.  
  16. 2. Open Intuition (and Exec) (required in patch functions)
  17.  
  18. 3. Allocate a SetFunc
  19.  
  20. 4. Initilise the SetFunc:
  21.     sf_Library : Library which the function is in.
  22.     sf_Offset : Offset of function from library, value can be obtained from
  23.       the libraries #?_pragmas.h file, for example the pragma for diskfont
  24.       library contains the following entry:
  25.       
  26.             #pragma libcall DiskfontBase OpenDiskFont 1e 801
  27.       
  28.       If you are to patch the OpenDiskFont() function then set sf_Library to
  29.       DiskfontBase, and sf_Offset to -0x1e (negative of first number after
  30.       the function name in the pragma (number is hex))
  31.     sf_Func : New function.
  32.     sf_QuitMethod,
  33.     sf_Count : see below.
  34.  
  35. 5. Call SFReplace(SetFunc)
  36.  
  37. 6. When finished call SFRestore(SetFunc)
  38.  
  39. A complete example which patches DisplayBeep() from intuition library is 
  40. included, type smake to compile.
  41.  
  42. NOTES ON QUITMETHOD
  43. ~~~~~~~~~~~~~~~~~~~
  44.  
  45. When restoring a patch there is no standard safe way. Safety can never be
  46. guaranteed. I have implemented 2 diferent quit methods. With the first
  47. (SFQ_WAIT) the function is restored and then waits for sf_Count seconds. 
  48. The other (SFQ_COUNT) restores the function and then waits until sf_Count = 0.
  49. With SFQ_COUNT your replacment function should increment sf_Count when it is
  50. entered and decrement it when it exits. See the example for more info.
  51.  
  52. WHAT CANNOT BE PATCHED
  53. ~~~~~~~~~~~~~~~~~~~~~~
  54.  
  55. Due to the method in which the patches are installed/removed you should not
  56. patch the following functions:
  57.  
  58.    exec.library   SetFunction()
  59.                   Forbid()
  60.                   Permit()
  61.                   CacheClearU()
  62.  
  63. DISTRIBUTION
  64. ~~~~~~~~~~~~
  65.  
  66. If you use SFPatch in your programs then please add a note to your docs to
  67. indicate this, and try to send me a copy of the program.
  68.  
  69. CONTACT
  70. ~~~~~~~
  71.  
  72. After september 95:
  73.    cs2lk@sal.scms.rgu.ac.uk
  74.  
  75. IRC: Wangi
  76.  
  77. Lee Kindness
  78. 8 Craigarn Road
  79. Portlethen
  80. Aberdeen
  81. AB1 4QR
  82. SCOTLAND
  83.  
  84. OTHER
  85. ~~~~~
  86.  
  87. SFPatch is a direct result of some of my recent programs: YourFault, NaeGrey
  88. and Wanginfo (download util/boot/YourFault.lha from aminet for a complete
  89. list of my 17 or so programs...)
  90.  
  91. Wangi! _\\//